\documentclass{article}
\usepackage{mathptmx}
\usepackage[linkcolor=black, colorlinks]{hyperref}
\usepackage{amsmath}
\usepackage{setspace}
\usepackage[margin=1in]{geometry}

\title{Installation Guide for the Toolkit for the Analysis of Composite Structures (TACS)}
\date{}
\author{Graeme Kennedy}

\begin{document}

\maketitle

\section{Introduction}

The Toolbox for the Analysis of Composite Structures (TACS) is a
parallel finite-element code written in C++, with an optional python
interface. TACS has been implemented from the start with gradient-based
optimization in mind. There are built-in routines for evaluating
functions of interest and their derivatives. TACS is object oriented
and can be extended to include new elements, constitutive properties
or functions of interest.

There are several software package dependencies required to install
TACS. The dependencies are divided into the following categories:
\begin{enumerate}
\item Dependencies for the C++ interface
\item Dependencies for the python interface
\end{enumerate}

\section{Checking out the code}

The development version of the TACS source is located at:
\url{https://bitbucket.org/gkennedy/tacs-dev}. Using mercurial, checkout the
source by typing \texttt{hg clone
  https://user@bitbucket.org/gkennedy/tacs-dev}

Also, download the file: \texttt{TACS\_extern.tar.gz} and place it in
the directory \texttt{extern}. Follow the
instructions in the \texttt{extern/README} file in this directory. Note also that
\texttt{f5totec} and \texttt{f5tovtk} are located in this directory as well.

The first step after checking out TACS is to copy
\texttt{Makefile.in.info} to \texttt{Makefile.in} in the TACS root
directory. \texttt{Makefile.in} contains the installation paths of the
libraries used by TACS. In particular, set \texttt{TACS\_DIR} to the
root directory of the TACS installation. I also recommend that you copy
the configuration script \texttt{setup.cfg.info} to \texttt{setup.cfg} 
for the python version of the code. The settings in \texttt{setup.cfg.info} 
are intended for development, if you are just going to use the code as-is,
you may wish to modify these settings.

\section{Installing the C++ interface}

TACS can be used as a stand-alone C++ code without the python-level
interface. The C++ source is located under \texttt{TACS/src}. 

The requirements for the installation are:
%
\begin{enumerate}
\item An MPI installation implementing the MPI 2.0 Standard
  \url{http://www.mcs.anl.gov/research/projects/mpi/}
\item \texttt{LAPACK}: The standard linear algebra package
\item \texttt{METIS 5.0}: Serial graph-partitioner
  \url{http://glaros.dtc.umn.edu/gkhome/metis/metis/overview}
\item \texttt{AMD}: A package for computing the minimum degree
  ordering \url{http://www.cise.ufl.edu/research/sparse/amd/}
  \begin{itemize}
  \item \texttt{UFconfig}: Required for the \texttt{AMD} package:
    \url{http://www.cise.ufl.edu/research/sparse/UFconfig/}
  \end{itemize}
\end{enumerate}

The external programs: \texttt{METIS}, \texttt{AMD}, \texttt{UFconfig}
and \texttt{TecIO} are part of \texttt{TACS\_extern.tar.gz} file.

Notes: An MPI 2.0 standard compliant compiler is essential. If one is
not available, the code will not compile correctly. When you
think everything is ready, type \texttt{make} in the TACS
directory. This makes all the TACS-only source.

\subsection{f5totec}

\texttt{f5totec} is an executable that converts the .f5 files output 
from TACS to a tecplot compatible format. Compiling \texttt{f5totec}
requires Tecplot's external library for generating binary files
directly

\begin{enumerate}
\item \texttt{TecIO}: Tecplot binary format conversion code
\end{enumerate}

I recommend putting \texttt{f5totec} on your path. One way is
to create a symbolic link in your local \texttt{bin} directory to
f5totec. Note that this utility converts one .f5 file at a time. The
usage is \texttt{f5totec input [output]}, if no output file is
specified, the output name is taken as the input name with the
extension .plt.

\subsection{f5tovtk}

\texttt{f5tovtk} is an executable that converts .f5 files to 
VTK format compatible with Paraview. It is also useful to put this
utility on your path if possible.

\subsection{Tutorial example}

There is a simple tutorial example in the \texttt{examples}
directory. Once the C++ interface has been compiled, try making
and running \texttt{plate\_example.c}.

\section{Installing the python interface}

The python interface is generated in the \texttt{tacs} sub-directory.
The interface is generated using Cython.

The python interface requires the following packages:
%
\begin{enumerate}
\item \texttt{numpy}: Numerical python packages
\item \texttt{mpi4py}: Python interface for MPI
\end{enumerate}

You will need a recent version of python - at least python2.5 or
greater (I have not tested with python 3.0). It is possible to install
a local version of python if an old version is installed.

\subsection{NumPy}

\texttt{numpy} is available from here \url{http://numpy.scipy.org/}. By default,
the Makefile.in determines the \texttt{numpy} installation directory 
from the python installation.

\subsection{mpi4py}
 
\texttt{mpi4py} can be downloaded from here:
\url{http://pythonhosted.org/mpi4py/}.  Install the package using:
\texttt{python setup.py build} then \texttt{python setup.py
  install}. If you don't have root access use either the
\texttt{prefix} or the \texttt{home} options to specify the local
installation location. By default, Makefile.in determines the 
\texttt{mpi4py} installation directory from the python
installation.

\subsection{Installing the \texttt{tacs} package}

To build the python interface to \texttt{tacs}, you can use the Makefile
or you can type the following command in the root directory:

\begin{verbatim}
python setup.py build_ext --inplace
\end{verbatim}

The \texttt{--inplace} option places the shared objects direclty in the source
directories.  This should build and place the files \texttt{TACS.so}, 
\texttt{elements.so}, \texttt{functions.so} and \texttt{constitutive.so} under the 
\texttt{tacs} sub-directory.

There are several options to make the python \texttt{tacs} package
available in python. These options consist of the following:

\begin{enumerate}
\item The way is to simply place the TACS root directory
on your \texttt{PYTHONPATH}. However, some python installations create their 
own environments, and do not use the \texttt{PYTHONPATH} environment variable.

\item An alternative is to use the development installation which
places the shared objects within the TACS directory with the source.
I recommend using the \texttt{--user} option which installs it locally
within your home directory, with a symbolic link to the share objects.
This can be performed by typing:

\begin{verbatim}
python setup.py develop --user
\end{verbatim}

\end{enumerate}


\end{document}
